Inside Macintosh: QuickTime Components
Applications that use QuickTime time bases may define callback functions that are associated with a specific time base. Applications can then use these callback functions to perform activities that are triggered by temporal events, such as a certain time being reached or a specified rate being achieved. The time base functions of the Movie Toolbox interact with clock components to schedule the invocation of these callback functions--your clock component is responsible for calling the callback function at its scheduled time.
The functions described in this section are called by the Movie Toolbox to support applications that define time base callback functions. For more information about time base callback functions, see the chapter "Movie Toolbox" in Inside Macintosh: QuickTime . Note that your clock component can delegate its callback events to another component by calling the Component Manager's DelegateComponent function, which is described in the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox .
The ClockNewCallBack function allows your clock component to allocate the memory to support a new callback event. When an application discards a callback event, the Movie Toolbox calls your clock component's ClockDisposeCallBack function.
The Movie Toolbox calls your clock component's ClockCallMeWhen function when an application wants to schedule a callback event. When the callback function is to be invoked to service the event, the Movie Toolbox calls your component's ClockCancelCallBack function so that you can remove the callback event from the list of scheduled events.
Your component's ClockNewCallBack function allocates the memory for a new callback event. The Movie Toolbox calls this function when an application defines a time base callback event with the Movie Toolbox's NewCallBack function. The callback event created at this time is not active until it has been scheduled. An application schedules a callback event by calling the Movie Toolbox's CallMeWhen function.
Your component allocates the memory required to support the callback event. The memory must be in a locked block and must begin with a callback header structure. This structure is described in "Data Type," which begins on Data Type .
You should not call this function at interrupt time.
pascal QTCallBack ClockNewCallBack (ComponentInstance aClock,
TimeBase tb,
short callBackType);
Your clock component allocates the memory for the event and returns a pointer to that memory. If your clock component cannot satisfy the request or detects invalid or unsupported parameter values, you should set the QTCallBack result to nil .
Your component can allocate an arbitrarily large piece of memory for the callback event. That memory must begin with a callback header structure, which must be initialized to 0.
Your clock component's ClockCallMeWhen function schedules a callback event for invocation. The Movie Toolbox calls this function when an application schedules a callback event using the CallMeWhen function of the Movie Toolbox (described in the chapter "Movie Toolbox" in Inside Macintosh: QuickTime ).
The Movie Toolbox passes the parameter data from its CallMeWhen function to your component in the param1 , param2 , and param3 parameters to this function. Your clock component interprets these parameters based on the value of the callBackType parameter to the ClockNewCallBack function (see ClockNewCallBack ).
pascal ComponentResult ClockCallMeWhen (ComponentInstance aClock,
QTCallBack cb,
long param1,
long param2,
long param3);
The Movie Toolbox maintains control information about the callback event. Your clock component only needs to maintain the invocation schedule. For example, the Movie Toolbox saves the address of the callback event, its reference constant, and the value of the A5 register. In addition, the Movie Toolbox prevents applications from scheduling a single callback event more than once.
If your clock component successfully schedules the callback event, you should call the AddCallBackToTimeBase function (described on AddCallBackToTimeBase ) to add it to the list of callback events for the corresponding time base. If your component cannot schedule the callback event, it should return an appropriate error.
Your clock component's ClockCancelCallBack function removes the specified callback event from the list of scheduled callback events for a time base.
pascal ComponentResult ClockCancelCallBack
(ComponentInstance aClock,
QTCallBack cb);
The Movie Toolbox calls this function when an application cancels its callback event by calling CancelCallBack . The Movie Toolbox also calls this function whenever it executes the callback event, thus removing it from the list of scheduled callback events. The application is then responsible for rescheduling the event, if appropriate.
If your clock component successfully cancels the callback event, you should call the RemoveCallBackFromTimeBase function, described on RemoveCallBackFromTimeBase , so that the Movie Toolbox can remove the callback event from its list of scheduled events.
Your clock component's ClockDisposeCallBack function disposes of the memory associated with the specified callback event.
pascal ComponentResult ClockDisposeCallBack
(ComponentInstance aClock,
QTCallBack cb);